enhancement: Add support for function args & kwargs type hints in ctx.run.

[objecthuman]

Add support for function args & kwargs type hints in ctx.run.

Description

This pr adds a new function run_typed in the context class. The function is a direct replacement to existing ctx.run function.

Why this change is introduced?

1. The run function does not support type hints for the action function's parameters.
2. The run function does not support keyword arguments for the action function.
3. These improvements address user feedback (Add support for function args & kwargs type hints in ctx.run. #108 ) for better developer experience and type safety.

Changes Introduced

Code changes

1. Add a new abstract method run_typed inside of context.py.
2. Added a new RunOptions dataclass to bundle all the additional parameters previously passed to ctx.run, now passed as a single parameter to run_typed.
3. The run function inside of context.py has been deprecated with typing_extensions.deprecated
4. Added implementation for run_typed inside of server_context.py
5. Tests have been updated to use ctx.run_typed instead of ctx.run.

Dependency changes

1. Add typing-extensions>=4.14.0 as direct dependency for the sdk, as this package helps in marking functions as deprecated.

Version changes

1. Bumped the sdk version from 0.8.0 to 0.9.0

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[objecthuman]

#108

[objecthuman]

I have read the CLA Document and I hereby sign the CLA

[objecthuman]

@igalshilman

[igalshilman]

Hey @objecthuman looks great, did an initial pass.
let's wait for CI.

[objecthuman]

@igalshilman looks like rust integration tests are failing.

[slinkydeveloper]

Hey this is the reason the test is failing:

2025-07-03T14:55:31.975756Z TRACE sys_state_set{key="awk-awk0" restate.invocation.id="inv_1jVtkIkLISpL1nA5vWLMeCiw312ZJIUBj5" restate.protocol.state="Replaying" restate.journal.command_index=0 restate.protocol.version=application/vnd.restate.invocation.v5}: restate_sdk_shared_core::vm: return=Ok(())
2025-07-03T14:55:31.978455Z DEBUG notify_error{error=Error { code: 500, message: "AttributeError(\"'str' object has no attribute 'serde'\")", stacktrace: "Traceback (most recent call last):\n\n  File \"/usr/local/lib/python3.12/site-packages/restate/server_context.py\", line 290, in enter\n    out_buffer = await invoke_handler(handler=self.handler, ctx=self, in_buffer=in_buffer)\n                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n  File \"/usr/local/lib/python3.12/site-packages/restate/handler.py\", line 231, in invoke_handler\n    out_arg = await handler.fn(ctx, in_arg) # type: ignore [call-arg, arg-type]\n              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n  File \"/usr/src/app/services/virtual_object_command_interpreter.py\", line 167, in interpret_commands\n    futures = [to_durable_future(ctx, c) for c in cmd['commands']]\n               ^^^^^^^^^^^^^^^^^^^^^^^^^\n\n  File \"/usr/src/app/services/virtual_object_command_interpreter.py\", line 121, in to_durable_future\n    res = ctx.run_typed(\"run should fail command\", side_effect, cmd['reason'])\n          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n  File \"/usr/local/lib/python3.12/site-packages/restate/server_context.py\", line 550, in run_typed\n    if isinstance(options.serde, DefaultSerde):\n                  ^^^^^^^^^^^^^\n\nAttributeError: 'str' object has no attribute 'serde'\n", related_command: None, next_retry_delay: None } command_relationship=None restate.invocation.id="inv_1jVtkIkLISpL1nA5vWLMeCiw312ZJIUBj5" restate.protocol.state="Processing" restate.journal.command_index=1 restate.protocol.version=application/vnd.restate.invocation.v5}: restate_sdk_shared_core::vm::transitions: Failed with error (500) AttributeError("'str' object has no attribute 'serde'")
Stacktrace: Traceback (most recent call last):

  File "/usr/local/lib/python3.12/site-packages/restate/server_context.py", line 290, in enter
    out_buffer = await invoke_handler(handler=self.handler, ctx=self, in_buffer=in_buffer)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  File "/usr/local/lib/python3.12/site-packages/restate/handler.py", line 231, in invoke_handler
    out_arg = await handler.fn(ctx, in_arg) # type: ignore [call-arg, arg-type]
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  File "/usr/src/app/services/virtual_object_command_interpreter.py", line 167, in interpret_commands
    futures = [to_durable_future(ctx, c) for c in cmd['commands']]
               ^^^^^^^^^^^^^^^^^^^^^^^^^

  File "/usr/src/app/services/virtual_object_command_interpreter.py", line 121, in to_durable_future
    res = ctx.run_typed("run should fail command", side_effect, cmd['reason'])
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  File "/usr/local/lib/python3.12/site-packages/restate/server_context.py", line 550, in run_typed
    if isinstance(options.serde, DefaultSerde):
                  ^^^^^^^^^^^^^

AttributeError: 'str' object has no attribute 'serde'

Seems something related to this change i guess?

[igalshilman]

@objecthuman fyi

[objecthuman]

added fixes could you pls re-run the ci? @igalshilman / @slinkydeveloper

[objecthuman]

@igalshilman all the checks have passed. when, who will merge the pr and can you also pls tell me how the release will take place?

[igalshilman]

@objecthuman merged! thanks a lot for your contribution, we’ll coordinate a release in the upcoming days.